package com.powerunion.datacollection.report.excelreport;

import java.util.Iterator;
import java.util.List;
import java.util.Map;

import com.powerunion.datacollection.report.excelreport.datasource.IDataSourceListener;


/**
 * 数据源数据访问接口，该接口是统一对外开放的数据源数据操纵接口，在外部程序操纵数据源时
 * 都通过该接口类来访问数据源。该接口提供了一个代理接口机制，可以保证在以后系统升级过程
 * 中能保证程序版本的兼容性。<br>
 * 注意：如果使用其他接口或类的函数来访问数据源，调用程序可能存在不能兼容ExcelReport后续
 * 升级版本的情况。
 * <br><br>
 * 使用示例： <br>
 * ...<br>
 * DataSource ds = (DataSource)dataSources.get("userDefinedDatasourceName");<br>
 * //向据源中添加数据。<br>
 * ds.addField("field1", "string value");<br>
 * ds.addField("field2", ObjectValue);<br>
 * ...<br>
 * //插入一条记录<br>
 * ds.addRecord();<br>
 * ...<br>
 * @author juny
 */
public interface DataSource extends IDataSourceListener{
    //数据访问类接口声明
    
    /**
     * 数据源数据记录游标移动到首记录。
     * @return true 游标移动到记录集的首记录位置; false 无法移动游标。
     */
    public boolean moveToFirst();
    
    /**
     * 记录集游标移动到下一条记录.
     * @return 成功则返回移动前的记录值。（注意：请不要通过这中方式来访问记录的值，
     * 因为该函数有可能会修改返回值的类型）
     */
    public Map next();
    
    /**
     * 判断是否还存在下一条记录.
     * @return true 记录集中还存在下一条记录。 false 记录集已经到最后一条记录。
     */
    public boolean hasNext();
    
    /**
     * 撤销移动到下一条记录操作，在分组中会用到。
     */
    public void undoNext();
    
    
    /**
     * 从当前记录集中取得指定字段值.
     * @param fieldName 字段名称
     * @return 返回字段值，以String方式表示。
     */
    public String getString(String fieldName);
    
    /**
     * 从当前记录集中取得指定字段值.以Object对象方式返回。
     * @param fieldName 字段名称
     * @return 成功 返回非空的Object对象； 失败 返回null。
     */
    public Object getValue(String fieldName);
    
    /**
     * 数据源中记录条数。
     * @return 返回记录条数。
     */
    public int size();
    
    /**
     * 获取遍历数据源的方法
     * @return
     */
    public Iterator iterator();
    
    
    //数据设置类接口声明
    
    /**
     * 添加字段数据.向当前记录中添加一个字段数据。
     * @param field 字段名称。
     * @param value 字段数据值
     * @return true 数据添加成功； false 数据添加失败。
     */
    public boolean addField(String field, Object value);
    
    
    /**
     * 修改数据源对象中当前记录的指定字段值。如果传入的字段不存在函数返回false。
     * 否则函数会将数据源对象当前记录集的字段值修改为value传入的值。
     * @param fieldName 要修改值的字段名称
     * @param value     字段的新的值。
     * @return          true：修改成功  false 修改失败
     */
    public boolean setFieldValue(String fieldName, Object value);
    
    
    /**
     * 在数据源中插入一条新记录.调用该操作后，会将先前插入的所有字段值作为一条记录插入到数据源中。
     * @return true 记录添加成功； false 记录添加失败。
     */
    public boolean addRecord();
    
    /**
     * 加入一条新的记录到数据源
     * @param map 记录集合Map
     * @return 返回是否成功。true 成功， false 失败。
     */
    public boolean addRecord(Map map);
    
    /**
     * 将一个List保存的记录集添加到数据源中，其中list 保存的是Map对象。
     * 每个Map对象保存一条记录。map中数据的存放格式
     * key=fieldName(字段名称)  value=fieldValue(字段值)
     * @param list
     */
    public void setRecordList(List list);
}
